Website audit
You are reading the Data API docs
baseurl:api.seranking.com 80cfee7d-xxxx-xxxx-xxxx-fc8500816bb3 (UUID format)253a73adxxxxxxxxxxxxxx340aa0a939 (40-char hex)The Website Audit API provides a comprehensive suite of tools to programmatically manage the full lifecycle of your technical SEO audits. These endpoints allow you to launch new crawls, monitor their progress, and retrieve detailed reports and page-level data.
Create an Audit
These endpoints launch a new website audit. Use the Standard endpoint for most websites, and the Advanced endpoint for sites that rely heavily on JavaScript to render content, such as Single-Page Applications (SPAs).
⚠️ Cost Information: Be aware of the cost difference before launching an audit.
- Standard Audits cost 2 credits per crawled page.
- Advanced Audits cost 20 credits per crawled page.
Create Standard Audit
Launches a standard audit that crawls the HTML of a website. This is suitable for most static and server-side rendered sites.
POST /v1/site-audit/audits/standard
POST Request
curl --location 'https://api.seranking.com/v1/site-audit/audits/standard' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token YOUR_API_KEY' \
--data '{
"domain": "example.com",
"title": "Standard Audit for Example.com",
"settings": {
"max_pages": 10000,
"source_subdomain": 0
}
}'
Create Advanced Audit
Launches an advanced audit that renders JavaScript before analyzing the page. Use this for single-page applications (SPAs) or any site where content is loaded dynamically.
POST /v1/site-audit/audits/advanced
POST Request
curl --location 'https://api.seranking.com/v1/site-audit/audits/advanced' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token YOUR_API_KEY' \
--data '{
"domain": "spa-example.com",
"title": "Advanced Audit for SPA-Example.com",
"settings": {
"max_pages": 100,
"source_subdomain": 1
}
}'
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| domain | string | yes | – | The domain to be audited. Example: domain.com |
| title | string | no | domain | A custom title for the audit report. Max 300 characters. |
| settings | object | no | – | An object containing specific audit settings. Only include parameters you want to override. See the Audit Settings table below. |
Audit Settings
The settings object allows for detailed customization of the website crawl. All parameters are optional and apply to both audit types.
| Name | Description | Possible Values | Default Value |
|---|---|---|---|
| source_site | Scan all pages by following internal links from the homepage. If 0, scans only from sitemap or a provided list. | 1 (yes), 0 (no) | 1 |
| source_sitemap | Scan the sitemap.xml file. | 1 (yes), 0 (no) | 1 |
| source_subdomain | Scan subdomains. If 0, subdomain links are treated as external. | 1 (yes), 0 (no) | 0 |
| source_file | Use a custom list of pages for the audit. | 1 (yes), 0 (no) | 0 |
| check_robots | Follow the directives in the robots.txt file. | 1 (yes), 0 (no) | 1 |
| ignore_params | Ignore URL parameters. | 0 (none), 1 (all), 2 (custom list) | 0 |
| custom_params | A list of URL parameters to ignore when ignore_params is 2. | Comma-separated string | utm_source, utm_medium, … |
| ignore_noindex | Ignore pages with a noindex tag. | 1 (yes), 0 (no) | 0 |
| ignore_nofollow | Ignore links with a nofollow attribute. | 1 (yes), 0 (no) | 0 |
| user_agent | The User-Agent header to use for the crawl. | 0-13 | 0 (SE Ranking bot) |
| login | Login for Basic HTTP Authentication. | String | null |
| password | Password for Basic HTTP Authentication. | String | null |
| max_pages | Maximum number of pages to crawl. | 1-300000 | 1000 |
| max_depth | Maximum crawl depth. | 1-100 | 10 |
| max_req | Maximum number of requests per second. | 1-500 | 500 |
| max_redirects | Maximum number of redirects to follow. | 1-50 | 5 |
| min_title_len | Minimum length for the <title> tag. | 1-10000 | 20 |
| max_title_len | Maximum length for the <title> tag. | 1-10000 | 65 |
| min_description_len | Minimum length for the meta description. | 1-10000 | 1 |
| max_description_len | Maximum length for the meta description. | 1-10000 | 158 |
| max_size | Maximum page size in kilobytes. | 1-100000 | 3000 |
| min_words | Minimum word count per page. | 1-10000 | 250 |
| max_h1_len | Maximum length for <h1> tags. | 1-10000 | 100 |
| max_h2_len | Maximum length for <h2> tags. | 1-10000 | 100 |
| allow | Only crawl URLs that start with this path. | String | null |
| disallow | Do not crawl URLs that start with this path. | String | null |
| hide | Hide URLs and resources that start with this path from the report. | String | null |
Response Parameters
If successful, the server returns a JSON object containing the unique ID for the newly created audit.
| Parameter | Data Type | Description | Example |
|---|---|---|---|
| id | integer | The unique identifier for the audit report. | 700237036 |
Example Request
curl --location 'https://api.seranking.com/v1/site-audit/audits/standard' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token 80cfee7d-d060-2b3c-a707-fc8500816bb3' \
--data '{
"domain": "example.com",
"title": "Example Audit Title",
"settings": {
"source_site": 1,
"source_sitemap": 1,
"source_subdomain": 0,
"source_file": 0,
"check_robots": 1,
"ignore_params": 0,
"custom_params": "utm_source,utm_medium,utm_term,utm_content,utm_campaign",
"ignore_noindex": 0,
"ignore_nofollow": 0,
"user_agent": 0,
"login": "",
"password": "",
"max_pages": 10000,
"max_depth": 10,
"max_req": 500,
"max_redirects": 5,
"min_title_len": 20,
"max_title_len": 65,
"min_description_len": 1,
"max_description_len": 158,
"max_size": 3000,
"min_words": 250,
"max_h1_len": 100,
"max_h2_len": 100
}
}'
Example Response
A successful request returns a JSON object containing the unique ID of the created audit.
{
"id": 700237036
}
List audits
This endpoint retrieves a list of all website audits associated with your account, providing key details and statistics for each.
GET Request
The request should be made as a GET request. You can use query parameters to paginate the results.
curl --location 'https://api.seranking.com/v1/site-audit/audits?limit=10&offset=0&search=booking.com&date_start=2025-07-01&date_end=2025-07-31' \
--header 'Authorization: Token YOUR_API_KEY'
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| limit | Integer | No | 100 | The number of audits to return in the list. |
| offset | Integer | No | 0 | The starting position (offset) for the list of audits. |
| search | String | No | – | Filters the list by a search term matching the audit’s title or URL. |
| date_start | String | No | – | The start date for filtering audits (YYYY-MM-DD). |
| date_end | String | No | – | The end date for filtering audits (YYYY-MM-DD). |
Response Parameters
If successful, the server returns a JSON object containing the total count of audits and an array of audit objects.
| Parameter | Data Type | Description |
|---|---|---|
| total | Integer | The total number of audits matching the filter criteria. |
| items | Array | An array of objects, each representing a website audit. |
Each object in the items array has the following structure:
| Parameter | Data Type | Description | Example |
|---|---|---|---|
| id | Integer | The unique identifier for the audit report. | 700138456 |
| url | String | The URL of the audited website. | http://booking.com |
| title | String | The title of the audit report. | booking.com |
| last_update | String | The date the audit was last updated (YYYY-MM-DD). | 2025-07-08 |
| status | String | The current status of the audit (e.g., finished, processing). | finished |
| stats | Object | An object containing the latest statistics for the audit (score, errors, warnings, notices, crawled). | { “score”: 69, “errors”: 2303, “warnings”: 3710, “notices”: 10875, “crawled”: 1830 } |
| prev_stats | Object | An object containing statistics from the previous audit run. Can be null if no prior data exists. | null |
Example Request
curl --location 'https://api.seranking.com/v1/site-audit/audits?limit=4&offset=0&search=booking.com&date_start=2025-07-01&date_end=2025-07-31' \
--header 'Authorization: Token YOUR_API_KEY'
Example Response
A successful request returns a JSON object containing the unique ID of the created audit.
{
"items": [
{
"id": 700138456,
"group_id": 0,
"url": "http://booking.com",
"title": "booking.com",
"has_project": true,
"site_id": 10113599,
"last_update": "2025-07-08",
"status": "finished",
"error": null,
"error_params": null,
"stats": {
"score": 69,
"errors": 2303,
"warnings": 3710,
"notices": 10875,
"crawled": 1830
},
"prev_stats": null,
"version": "2.0",
"owner_account_id": 4242308,
"is_new": 1
}
],
"total": 1
}
Get Audit Status
This endpoint allows you to check the real-time status of a specific website audit, whether it’s queued, currently processing, or already finished. This is useful for monitoring the progress of a crawl before fetching the full report.
GET Request
The request should be made as a GET request with the audit_id included in the query string.
curl --location 'https://api.seranking.com/v1/site-audit/audits/status?audit_id=700183831' \
--header 'Authorization: Token YOUR_API_KEY'
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| audit_id | Integer | Yes | – | The unique identifier of the audit to check. |
Response Parameters
If successful, the server returns a JSON object containing the current status and key metrics of the audit.
| Parameter | Data Type | Description |
|---|---|---|
| status | String | The current status of the audit. Possible values: queued, processing, finished, cancelled, expired. |
| total_pages | Integer | The number of pages crawled so far. |
| total_errors | Integer | The current count of critical issues found. |
| total_warnings | Integer | The current count of warnings found. |
| total_passed | Integer | The current count of checks that have passed. |
| start_time | String | The timestamp for when the audit began. |
| audit_time | String | The timestamp for when the audit was completed. This will be present if the status is finished. |
Example Request
curl --location 'https://api.seranking.com/v1/site-audit/audits/status?audit_id=700183831' \
--header 'Authorization: Token YOUR_API_KEY'
Example Response
{
"total_pages": 1009,
"total_warnings": 979,
"total_errors": 346,
"total_passed": 77,
"status": "finished",
"start_time": "2025-07-29 11:06:23",
"audit_time": "2025-07-29 11:19:33"
}
Get audit report
This endpoint retrieves the full, detailed report for a completed website audit. The report includes the site’s overall health score, domain properties, and a section-by-section breakdown of all checks performed, categorized by issue type (errors, warnings, notices).
GET Request
The request should be made as a GET request with the audit_id included in the query string.
curl --location 'https://api.seranking.com/v1/site-audit/audits/report?audit_id=700183831' \
--header 'Authorization: Token YOUR_API_KEY'
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| audit_id | Integer | Yes | – | The unique identifier of the audit for which to retrieve the report. |
Response Parameters
If successful, the server returns a JSON object containing the complete audit report.
| Parameter | Data Type | Description |
|---|---|---|
| is_finished | Boolean | Indicates if the audit has completed. The report is only available if this is true. |
| score_percent | Integer | The overall health score of the website, from 0 to 100. |
| total_pages | Integer | The total number of pages crawled during the audit. |
| total_errors | Integer | The total count of critical issues found. |
| total_warnings | Integer | The total count of warnings found. |
| total_notices | Integer | The total count of minor issues or notices. |
| total_passed | Integer | The total count of checks that passed successfully. |
| audit_time | String | The timestamp for when the audit was completed. |
| domain_props | Object | An object containing general data about the audited domain. See details below. |
| sections | Array | An array of objects, where each object represents a category of audit checks (e.g., Security, Content). |
domain_props Object
| Parameter | Data Type | Description |
|---|---|---|
| expdate | String | The expiration date of the domain registration. |
| backlinks | String | The total number of backlinks pointing to the domain. |
| index_google | String | The number of pages indexed in Google. |
sections Array Each object in the sections array contains a uid (unique ID), a name for the category, and a props object. The props object lists all the individual checks for that category. Each check includes:
- code: A unique identifier for the check (e.g., no_https).
- status: The result of the check (error, warning, notice, passed).
- name: A human-readable name for the check.
- value: The number of pages affected by this issue.
Example Request
curl --location 'https://api.seranking.com/v1/site-audit/audits/report?audit_id=700183831' \
--header 'Authorization: Token YOUR_API_KEY'
Example Response
{
"total_pages": 1009,
"total_warnings": 979,
"total_errors": 346,
"total_passed": 77,
"total_notices": 3915,
"is_finished": true,
"domain_props": {
"dt": 44,
"domain": "www.vitality.co.uk",
"domains": "3401",
"expdate": "2025-08-30",
"updated": "2025-07-29 12:07:28",
"backlinks": "212249",
"index_bing": 15500,
"all_checked": true,
"index_yahoo": 15500,
"index_google": "1380"
},
"sections": [
{
"uid": "security_v2",
"name": "Security",
"props": {
"no_https": {
"code": "no_https",
"status": "error",
"name": "No HTTPS encryption",
"value": 0
},
"mixed_content": {
"code": "mixed_content",
"status": "error",
"name": "Mixed content",
"value": 0
}
}
},
{
"uid": "crawling_v2",
"name": "Crawling & Indexing",
"props": {
"http4xx": {
"code": "http4xx",
"status": "error",
"name": "4XX HTTP Status Codes",
"value": 28
},
"blocked_by_noindex": {
"code": "blocked_by_noindex",
"status": "notice",
"name": "Blocked by noindex",
"value": 34
}
}
}
],
"score_percent": 80,
"audit_time": "2025-07-29 11:19:33",
"version": "2.0"
}
Get audit pages by issue
This endpoint retrieves a paginated list of all URLs affected by a specific issue within a given audit. You can identify the code for an issue by first fetching the main audit report.
GET Request
The request should be made as a GET request with all parameters included in the query string.
curl --location 'https://api.seranking.com/v1/site-audit/audits/pages?code=title_duplicate&audit_id=700183831&limit=10&offset=0' \
--header 'Authorization: Token YOUR_API_KEY'
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| audit_id | Integer | Yes | – | The unique identifier of the audit report. |
| code | String | Yes | – | The unique code for the issue (e.g., title_duplicate). |
| limit | Integer | No | 100 | The number of URLs to return in the list. |
| offset | Integer | No | 0 | The starting position (offset) for the list of URLs. |
Response Parameters
If successful, the server returns a JSON object containing the total count of affected URLs and an array of the URLs themselves.
| Parameter | Data Type | Description |
|---|---|---|
| total_urls | Integer | The total number of URLs affected by this specific issue. |
| urls | Array | An array of strings, where each string is a URL affected by the issue. |
| urls_type | String | Describes the format of the urls array. For this endpoint, it is typically simple_urls_array. |
Example Request
curl --location 'https://api.seranking.com/v1/site-audit/audits/pages?code=title_duplicate&audit_id=700183831&limit=10&offset=0' \
--header 'Authorization: Token YOUR_API_KEY'
Example Response
A successful request returns a JSON object containing the unique ID of the created audit.
{
"total_urls": 143,
"urls": [
"https://www.vitality.co.uk/life-insurance/accident-and-fracture-cover/",
"https://www.vitality.co.uk/business/health-insurance/callback/",
"https://www.vitality.co.uk/media/vitality-employee-challenges-programme-goes-live/",
"https://www.vitality.co.uk/media/bbq-blunders-the-bbq-foods-fooling-brits/",
"https://www.vitality.co.uk/media/vitality-launches-cpd-accredited-sustainability-webinar-series-for-advisers/",
"https://www.vitality.co.uk/media/vitality-welcomes-new-partners-to-the-programme/",
"https://www.vitality.co.uk/media/sneezing-season-slams-first-time-sufferers/",
"https://www.vitality.co.uk/media/vitality-calls-for-greater-focus-on-burnout/",
"https://www.vitality.co.uk/media/vitality-research-reveals-gaps-in-employee-awareness-of-sick-leave-policies/",
"https://www.vitality.co.uk/media/vitality-parkrun-celebrate-record-breaking/"
],
"urls_type": "simple_urls_array"
}
Get audit history by date
This endpoint retrieves a historical snapshot of a specific audit run, providing the full context of that audit, including the settings used, domain data at the time, and a summary of all issues found.
GET Request
The request should be made as a GET request with all parameters included in the query string.
curl --location 'https://api.seranking.com/v1/site-audit/audits/history?audit_id=700183831&date=2025-07-29' \
--header 'Authorization: Token YOUR_API_KEY'
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| audit_id | Integer | Yes | – | The unique identifier of the audit. |
| date | String | Yes | – | The specific date of the historical audit to retrieve (YYYY-MM-DD). |
Response Parameters
If successful, the server returns a JSON object containing the complete historical data for the specified audit run.
| Parameter | Data Type | Description |
|---|---|---|
| audit_time | String | The exact timestamp when the historical audit was completed. |
| domain_data | Object | An object containing general data about the domain at the time of the audit (e.g., backlinks, indexed pages). |
| settings | Object | An object detailing all the configuration settings that were used for this specific audit run. |
| pages_data | Object | An object where each key is an issue code (e.g., title_duplicate) and the value is the number of pages affected by that issue. |
| totals | Object | An object summarizing the final counts for the audit (total_pages, total_warnings, total_errors). |
Example Request
curl --location 'https://api.seranking.com/v1/site-audit/audits/history?audit_id=700183831&date=2025-07-29' \
--header 'Authorization: Token YOUR_API_KEY'
Example Response
A successful request returns a JSON object containing the unique ID of the created audit.
{
"audit_time": "2025-07-29 11:19:33",
"domain_data": {
"dt": 44,
"domain": "www.vitality.co.uk",
"backlinks": "212249",
"index_google": "1380"
},
"settings": {
"source_site": 1,
"source_sitemap": 1,
"max_pages": 1000,
"max_depth": 10
},
"pages_data": {
"css3xx": 1,
"css_big": 880,
"h1_long": 19,
"http4xx": 28,
"title_duplicate": 143,
"description_duplicate": 169
},
"totals": {
"total_pages": 1009,
"total_warnings": 979,
"total_errors": 346,
"total_passed": 77
},
"version": "2.0"
}
Update Audit Title
This endpoint allows you to change the title of an existing website audit report.
PATCH Request
The request should be made as a PATCH request. The ID of the audit to be updated is passed as a query parameter, and the new title is sent in the JSON request body.
curl --location --request PATCH 'https://api.seranking.com/v1/site-audit/audits?audit_id=89263' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token YOUR_API_KEY' \
--data '{
"title": "New Example Audit Title"
}'
Request Parameters
Query Parameter
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| audit_id | Integer | Yes | – | The unique identifier of the audit to update. |
Body Parameter
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| title | String | Yes | – | The new title for the audit report. Max 300 characters. |
Response Parameters
If successful, the server returns an HTTP 200 OK status code with an empty response body, confirming that the title has been updated.
Example Request
curl --location --request PATCH 'https://api.seranking.com/v1/site-audit/audits?audit_id=89263' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token YOUR_API_KEY' \
--data '{
"title": "New Title for Ananda Ioga Audit"
}'
Example Response
A successful request returns an empty response with a 200 OK status code.
[]
Delete Audit
This endpoint permanently deletes a specified website audit report and all of its associated data. This action cannot be undone.
DELETE Request
The request should be made as a DELETE request with the audit_id of the report to be deleted included in the query string.
curl --location --request DELETE 'https://api.seranking.com/v1/site-audit/audits?audit_id=89263' \
--header 'Authorization: Token YOUR_API_KEY'
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| audit_id | Integer | Yes | – | The unique identifier of the audit to delete. |
Response
If successful, the server returns an HTTP 200 OK status code with an empty response body, confirming that the audit has been deleted.
Example Request
curl --location --request DELETE 'https://api.seranking.com/v1/site-audit/audits?audit_id=89263' \
--header 'Authorization: Token YOUR_API_KEY'
Example Response
A successful request returns an empty response with a 200 OK status code.
[]
Recheck Audit
These endpoints initiate a new crawl for a previously completed audit, using the same settings as the original run. This is useful for tracking changes and verifying that issues have been resolved.
⚠️ Cost Information: Rechecking an audit incurs the same cost as creating a new one.
- Standard Audits cost 2 credits per crawled page.
- Advanced Audits cost 20 credits per crawled page.
Recheck Standard Audit
Launches a new standard crawl for an existing audit.
POST /v1/site-audit/audits/recheck/standard
Recheck Advanced Audit
Launches a new advanced crawl with JavaScript rendering for an existing audit.
POST /v1/site-audit/audits/recheck/advanced
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| audit_id | string | yes | – | The unique identifier of the audit to recheck. This is passed as a query parameter. |
Response
If successful, the server returns an HTTP 200 OK status code with an empty response body, confirming that the recheck has been initiated.
Example Request
Standard Recheck
curl --location --request POST 'https://api.seranking.com/v1/site-audit/audits/recheck/standard?audit_id=700237033' \
--header 'Authorization: Token YOUR_API_KEY'
Advanced Recheck
curl --location --request POST 'https://api.seranking.com/v1/site-audit/audits/recheck/advanced?audit_id=700237033' \
--header 'Authorization: Token YOUR_API_KEY'
Example Response
A successful request returns an empty response with a 200 OK status code.
[]
